feat: add Markdown formatter #2148
Conversation
|
📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/18355542046/artifacts/4218998745 |
|
@josevalim any thoughts here thus far? |
|
Sorry, a bit busy with Elixir v1.19-rc and today I was out of focus. It is in my inbox and I will review it as soon as I can. |
There was a problem hiding this comment.
Hey @yordis that's amazing! Let me share some ideas that could be useful.
I was inspecting the generated Markdown files and thinking if we could apply some changes. See the differences here https://gist.github.com/leandrocp/ee4f0ba8325b410b8650ccd26b9b2351 (CompiledWithDocs.md vs CompiledWithDocs_PROPOSAL.md)
- Use frontmatter block to describe global values/notes
- Use the format "Summary / Functions" similar to HTML pages (so Functions become a level 2 heading)
- Include source links
- Reorganize metadata, for eg: add (deprecated) and doc in summary
- Remove links to hexdocs.pm because 1) it breaks the content and I guess that would make it harder for LLMs to parse; 2) I'm not sure it should link to html pages
You can see some examples on https://shopify.dev/docs/api/liquid/basics.md and https://vercel.com/docs/rest-api/reference/sdk.md
yordis
force-pushed
the
yordis/add-markdown-formatter
branch
from
e1c6f8f to
a6870e3
Compare
|
@leandrocp thanks for the help, about the formatting, I do not have any strong opinions of the final output, I will leave it to @josevalim and you to decide on that front, I can adjust it |
Signed-off-by: Yordis Prieto <[email protected]>
yordis
force-pushed
the
yordis/add-markdown-formatter
branch
from
a6870e3 to
5131f1a
Compare
|
Just a heads up I am on holidays. This is still on top of my list but I cannot promise anything until I am back (next Wednesday). Sorry! |
|
Hey @yordis no strong opinions either, just trying to figure out a format that presents all the info. Regarding links, just to be clear it should contain links eventually but I believe that HexDocs must define how to serve Markdown pages first, for eg something like https://hexdocs.pm/elixir/1.18.4/Enum.md |
|
Some additional context: ExDoc is not tied to HexDocs and vice versa. We should design links with the assumptions it is served by any static host. I am thinking just using Enum.md with an anchor, same as html, is fine though? The anchor won’t actually work, but at least it is some context? |
Yeah it seems appropriate. Shopify docs links to "canonical" URLs, for eg in https://shopify.dev/docs/api/liquid/tags/form you can see a bunch of anchor links, but in the .md docs (https://shopify.dev/docs/api/liquid/tags/form.md) they are rendered as Vercel is not much different, they include relative links inside .md docs, for eg Claude use relative links with anchors, for eg in https://docs.claude.com/en/docs/build-with-claude/prompt-caching you can see a link |
Signed-off-by: Yordis Prieto [email protected]